home *** CD-ROM | disk | FTP | other *** search
/ MacHack 2000 / MacHack 2000.toast / pc / The Hacks / MacHacksBug / Python 1.5.2c1 / Tools / faqwiz / README < prev   
Encoding:
Text File  |  2000-06-23  |  4.7 KB  |  114 lines
  1. FAQ Wizard
  2. ----------
  3.  
  4. Author: Guido van Rossum <guido@python.org>
  5. Version: 1.0
  6. Date:  6 April 1998
  7.  
  8.  
  9. This is a CGI program that maintains a user-editable FAQ.  It uses RCS
  10. to keep track of changes to individual FAQ entries.  It is fully
  11. configurable; everything you might want to change when using this
  12. program to maintain some other FAQ than the Python FAQ is contained in
  13. the configuration module, faqconf.py.
  14.  
  15. Note that the bulk of the code is not an executable script; it's an
  16. importable module.  The actual script in cgi-bin is minimal.
  17.  
  18. Files:
  19.  
  20. faqw.py        executable script to be edited and installed in cgi-bin
  21. faqwiz.py    main module, lives in same directory as FAQ entry files
  22. faqconf.py    main configuration module
  23. faqcust.py    additional local customization module (optional)
  24.  
  25.  
  26. What's New?
  27. -----------
  28.  
  29. Version 1.0 corrects some minor bugs and uses tab-agnostic
  30. indentation; it is otherwise unchanged from version 0.9.0.
  31.  
  32. Version 0.9.0 uses the re module (Perl style regular expressions) for
  33. all its regular expression needs, instead of the regex and regsub
  34. modules (Emacs style).  This affects the syntax for regular
  35. expressions entered by the user as search strings (with "regular
  36. expression" checked), hence the version number jump.
  37.  
  38.  
  39. Setup Information
  40. -----------------
  41.  
  42. This assumes you are familiar with Python, with your http server, and
  43. with running CGI scripts under your http server.  You need Python 1.5
  44. or better.
  45.  
  46. Select a place where the Python modules that constitute the FAQ wizard
  47. will live (the directory where you unpacked it is an obvious choice).
  48. This will be called the SRCDIR.  This directory should not be writable
  49. by other users of your system (since they would be able to execute
  50. arbitrary code by invoking the FAQ wizard's CGI script).
  51.  
  52. Create a dedicated working directory, preferably one that's not
  53. directly reachable from your http server.  This will be called the
  54. FAQDIR.  Create a subdirectory named RCS.  Make both the working
  55. directory and the RCS subdirectory wrld-writable.  (This is essential,
  56. since the FAQ wizard runs as use nobody, and needs to create
  57. additional files here!)
  58.  
  59. Edit faqconf.py to reflect your setup.  You only need to edit the top
  60. part, up till the line of all dashes.  The comments should guide you
  61. in your edits.  (Actually, you can also choose to add your changes to
  62. faqcust.py and leave faqconf.py alone.  This is essential if you are
  63. maintaining multiple FAQs; see below.)
  64.  
  65. Don't forget to edit the SECTION_TITLES variables to reflect the set
  66. of section titles for your FAQ!
  67.  
  68. Next, edit faqw.py to reflect the pathname of your Python interpreter
  69. and the values for SRCDIR and FAQDIR that you just chose.  Then
  70. install faqw.py in your cgi-bin directory.  Make sure that it is
  71. world-executable.  You should now be able to connect to the FAQ wizard
  72. by entering the following URL in your web client (subsituting the
  73. appropriate host and port for "your.web.server", and perhaps
  74. specifying a different directory for "cgi-bin" if local conventions so
  75. dictate):
  76.  
  77.     http://your.web.server/cgi-bin/faqw.py
  78.  
  79. If you are unable to get this working, check your server's error_log
  80. file.  The documentation for Python's cgi module in the Python Library
  81. Reference Manual gives plentyu additional information about installing
  82. and debugging CGI scripts, including setup debugging.  This
  83. documentation is repeated in the doc string in the cgi module; try
  84. ``import cgi; print cgi.__doc__''.
  85.  
  86. Assuming this works, you should now be able to add the first entry to
  87. your FAQ using the FAQ wizard interface.  This creates a file
  88. faq01.001.htp in your working directory and an RCS revision history
  89. file faq01.001.htp,v in the RCS subdirectory.  You can now exercise
  90. the other FAQ wizard features (search, index, whole FAQ, what's new,
  91. roulette, and so on).
  92.  
  93.  
  94. Maintaining Multiple FAQs
  95. -------------------------
  96.  
  97. If you have multiple FAQs, you need a separate FAQDIR per FAQ, and a
  98. different customization file per FAQ.  The easiest thing to do would
  99. be to have the faqcust.py for each FAQ live in the FAQDIR for that
  100. FAQ, but that creates some security concerns, since the FAQDIR must be
  101. world writable: *if* someone who breaks into your system (or a
  102. legitimate user) manages to edit the faqcust.py file they can get
  103. arbitrary code to execute through the FAQ wizard.  Therefore, you will
  104. need a more complex setup.
  105.  
  106. The best way is probably to have a directory that is only writable by
  107. you for each FAQ, where you place the copy of faqcust.py for that FAQ,
  108. and have a world-writable subdirectory DATA for the data.  You then
  109. set FAQDIR to point to the DATA directory and change the faqw.py
  110. bootstrap script to add FAQDIR/.. to sys.path (in front of SRCDIR, so
  111. the dummy faqcust.py from SRCDIR is ignored).
  112.  
  113. --Guido van Rossum (home page: http://www.python.org/~guido/)
  114.